lists: Mention list style classes in docs

Document that GtkListView, GtkColumnView and GtkListBox
support .rich-list, .navigation-sidebar and .data-table
style classes.

diff --git a/docs/reference/gtk/images/data-table.png b/docs/reference/gtk/images/data-table.png
new file mode 100644 (file)
index 0000000..60eb959
Binary files /dev/null and b/docs/reference/gtk/images/data-table.png differ

diff --git a/docs/reference/gtk/images/navigation-sidebar.png b/docs/reference/gtk/images/navigation-sidebar.png
new file mode 100644 (file)
index 0000000..5a9b994
Binary files /dev/null and b/docs/reference/gtk/images/navigation-sidebar.png differ

diff --git a/docs/reference/gtk/images/rich-list.png b/docs/reference/gtk/images/rich-list.png
new file mode 100644 (file)
index 0000000..edfece1
Binary files /dev/null and b/docs/reference/gtk/images/rich-list.png differ

diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index aa4b7f8673fd850944ec361a33968a87d94168de..431192c2c65050608150bdb923647e5a5bdb7f86 100644 (file)
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -370,6 +370,9 @@ images = [
   'images/widget-hvalign.png',
   'images/window-default.png',
   'images/window.png',
+  'images/rich-list.png',
+  'images/data-table.png',
+  'images/navigation-sidebar.png'
 ]
 
 content_files = [

diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md
index 53d25f085366eb5c924379f54ea5e61951844019..b93ab872e3fc470650b07155a6ead3bb10182bf4 100644 (file)
--- a/docs/reference/gtk/section-list-widget.md
+++ b/docs/reference/gtk/section-list-widget.md
@@ -165,6 +165,30 @@ rows and provide a similar experience to #GtkTreeView.
 Developers should refer to those objects' API reference for more discussion
 on the topic.
 
+## List styles {#list-styles}
+
+One of the advantages of the new list widgets over #GtkTreeViews and cell
+renderers is that they are fully themable using GTK CSS. This provides a
+lot of flexibility. The themes that ship with GTK provide a few predefined
+list styles that can be used in many situations:
+
+![Rich list](rich-list.png)
+
+This style of list is low density, spacious and uses an outline focus ring.
+It is suitable for lists of controls, e.g. in preference dialogs or
+settings panels. Use the .rich-list style class.
+
+![Navigation sidebar](navigation-sidebar.png)
+
+This style of list is medium density, using a full background to indicate
+focus and selection. Use the .navigation-sidebar style class.
+
+![Data table](data-table.png)
+
+This style of list is a high density table, similar in style to a traditional
+treeview. Individual cells can be selectable and editable. Use the .data-table
+style class.
+
 ## Comparison to GtkTreeView
 
 Developers familiar with #GtkTreeView may wonder how this way of doing lists

diff --git a/gtk/gtkcolumnview.c b/gtk/gtkcolumnview.c
index 176481f2bae171b811ff57df79ec01c595647778..deadfd7b9e9ccb693bba1f929ea3b7218feccbb6 100644 (file)
--- a/gtk/gtkcolumnview.c
+++ b/gtk/gtkcolumnview.c
@@ -80,7 +80,7 @@
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
- * columnview[.column-separators]
+ * columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table]
  * ├── header
  * │   ├── <column header>
  * ┊   ┊
@@ -101,6 +101,10 @@
  * #GtkColumnView:show-row-separators is set, it will be passed on to the
  * list view, causing its CSS node to carry the .separators style class.
  * For rubberband selection, a node with name rubberband is used.
+ *
+ * The main columnview node may also carry style classes to select
+ * the style of [list presentation](ListContainers.html#list-styles):
+ * .rich-list, .navigation-sidebar or .data-table.
  */
 
 struct _GtkColumnView

diff --git a/gtk/gtklistbox.c b/gtk/gtklistbox.c
index fd0a86e4d28d668a90e6383af88cdb3c58fbfee7..98af2f58fa311a94fe107011dbd4b3e32ba040d2 100644 (file)
--- a/gtk/gtklistbox.c
+++ b/gtk/gtklistbox.c
@@ -75,14 +75,18 @@
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
- * list[.separators]
+ * list[.separators][.rich-list][.navigation-sidebar]
  * ╰── row[.activatable]
  * ]|
  *
- * GtkListBox uses a single CSS node named list. It may carry the .separators style
- * class, when the #GtkListBox:show-separators property is set. Each GtkListBoxRow uses
- * a single CSS node named row. The row nodes get the .activatable
- * style class added when appropriate.
+ * GtkListBox uses a single CSS node named list. It may carry the .separators
+ * style class, when the #GtkListBox:show-separators property is set. Each
+ * GtkListBoxRow uses a single CSS node named row. The row nodes get the
+ * .activatable style class added when appropriate.
+ *
+ * The main list node may also carry style classes to select
+ * the style of [list presentation](ListContainers.html#list-styles):
+ * .rich-list, .navigation-sidebar or .data-table.
  */
 
 typedef struct _GtkListBoxClass   GtkListBoxClass;

diff --git a/gtk/gtklistview.c b/gtk/gtklistview.c
index e0a33b42f4beefc0a44b36d6a7cac455ebf26a78..aa32b4686545ebd2548112cc6d4fab590abefae6 100644 (file)
--- a/gtk/gtklistview.c
+++ b/gtk/gtklistview.c
@@ -118,7 +118,7 @@
  * # CSS nodes
  *
  * |[<!-- language="plain" -->
- * listview[.separators]
+ * listview[.separators][.rich-list][.navigation-sidebar][.data-table]
  * ├── row
  * │
  * ├── row
@@ -132,6 +132,10 @@
  * .separators style class, when #GtkListView:show-separators property
  * is set. Each child widget uses a single CSS node named row. For
  * rubberband selection, a node with name rubberband is used.
+ *
+ * The main listview node may also carry style classes to select
+ * the style of [list presentation](ListContainers.html#list-styles):
+ * .rich-list, .navigation-sidebar or .data-table.
  */
 
 typedef struct _ListRow ListRow;